-- card: 3035 from stack: in.2 Stack
-- bmap block id: 0
-- flags: 0000
-- background id: 2669
-- name:  idle


-- part 4 (field)
-- low flags: 05
-- high flags: 0007
-- rect: left=2 top=2 right=240 bottom=318
-- title width / last selected line: 0
-- icon id / first selected line: 0 / 0
-- text alignment: 0
-- font id: 16
-- text size: 14
-- style flags: 0
-- line height: 18
-- part name: 
----- HyperTalk script -----
on mousewithin
  HCBalloon "This field explains the HCBalloon XCMD.", 50, 30
end mousewithin

on mousedown
  if the clicktext is "variation code" then
    visual effect iris open
    go next card
  end if
end mousedown



-- part 6 (button)
-- low flags: 00
-- high flags: 8000
-- rect: left=61 top=245 right=294 bottom=155
-- title width / last selected line: 0
-- icon id / first selected line: 21921 / 21921
-- text alignment: 1
-- font id: 0
-- text size: 12
-- style flags: 0
-- line height: 16
-- part name: Toggle Balloon Help
----- HyperTalk script -----
on mouseUp
  if the icon of me is "1290" then
    HCBalloon "off"
    set the icon of me to "big off"
  else
    HCBalloon "on"
    set the icon of me to "big on"
  end if
end mouseUp

on mousewithin
  HCBalloon "Click this button to turn Balloon Help off.", 36,44,6
end mousewithin




-- part 9 (button)
-- low flags: 00
-- high flags: A000
-- rect: left=185 top=245 right=293 bottom=239
-- title width / last selected line: 0
-- icon id / first selected line: 1008 / 1008
-- text alignment: 1
-- font id: 0
-- text size: 12
-- style flags: 0
-- line height: 16
-- part name: Print docs
----- HyperTalk script -----
on mouseUp
  print cd fld 1
end mouseUp

on mousewithin
  HCBalloon "Click here to print out the documentation in the scrolling" && "field.", 45, 40, 5
end mousewithin


-- part contents for card part 4
-- note: style data is present
----- text -----

HCBalloon 1.2 XCMD
by Len Saaf ©1991, Raleigh Associates

This XCMD may be used without cost if used in non-commercial stacks. It is freely distributable.

HCBalloon is a simple XCMD that provides Balloon Help for Hypercard stacks. It can also turn Balloon Help on and off and can check to see if  Balloon Help is active. You can also specify the position of the balloon's tip and the place where the tip joins the balloon. HCBalloon is compatible with the Helium system extension. Help balloons are not available on systems prior to 7.0. However, this XCMD will not crash systems prior to 7.0. The size of the XCMD is 2752 bytes.


Usage:

HCBalloon message [, x-offset, y-offset 
    [, variation code]]

Copy the XCMD to a stack and use the following syntax to add balloon help to a button or a field:

on MouseWithin
    HCBalloon "This text appears in ¬
    a help balloon."
end MouseWithin

That's all there is to it. Of course, you need to have Balloon Help turned on or it won't work! The balloon will disappear when the cursor leaves the rect of the target (the target means the button or field for which help is being provided). If that’s all you want to do then stop reading now! :–)

To turn Balloon Help on with the XCMD:

    HCBalloon "on"

To turn Balloon Help off:

    HCBalloon "off"

To check the status of Balloon Help (an example):

    HCBalloon "query"
    if the result is "true" then
      put "Balloon Help is on."
    else
      put "Balloon Help is off."
    end if

The x-offset and y-offset values specify the distance left and above the lower right corner of the target where the tip of the help balloon will appear. By default the tip of the help balloon is located at the lower right corner of the target. To put the tip a little closer to the center of the target, specify a small x- and y-offset. For example:

    HCBalloon "This is help.", 10, 10

You can also chooses a particular balloon style by specifying a variation code.  (To see the different balloon styles, click on the grouped text that is underlined above.) For example, say you have a button that is 60 pixels wide and 50 pixels high. Suppose you want the help balloon to appear at the upper left corner of the button. This would do the trick:

    HCBalloon "More help.", 60, 50, 5


Any errors encountered are reported in the result. If a balloon is displayed successfully, the result is empty. Here are the errors and diagnostics returned:

HCBalloon error: Wrong number of arguments

The number of arguments should be 1, 3, or 4.

HCBalloon error: HMSetBalloons error

An error was returned from the HMSetBalloons toolbox call.

HCBalloon error: HMShowBalloon error

An error was returned from the HMShowBalloon toolbox call.

HCBalloon error: System 7.0 or higher required for balloon help

HCBalloon error: A balloon is already showing

HCBalloon doesn't display a balloon if another is already showing.

HCBalloon error: Balloon help is turned off



Thanks to Larry Slack for testing and suggestions!

Bug reports and/or comments are welcome.

Len Saaf
52 Raleigh St.
Rochester, NY 14620

saaf@joker.optics.rochester.edu